Easy Deployment with GitOps and Argo CD

May 29, 2019 · 34 min read

Front End Developer @ Tech4Biz Solutions Pvt Ltd.

Introduction

Argo CD is like a helpful tool for making sure your apps work smoothly on Kubernetes, a system for managing applications. With Argo CD, you keep your app details in a clear and organized way, making it easy to see how everything is set up. It's kind of like using a special folder to keep all your important instructions for your apps.

Think of Argo CD as your assistant in charge of making sure your apps are running well. It follows a simple rule: store all your app details in a special place called Git, just like you store your documents in a folder on your computer. This way, everything is neat and easy to manage.

Argo CD works by checking this special folder in Git, and if it finds any changes or updates, it makes sure your apps in Kubernetes stay in sync with these changes. So, you don't have to worry about keeping everything in order – Argo CD does it for you!

When working with Argo CD, you can use different ways to describe how your applications should run:

Kustomize Applications: Think of this as adjusting settings for your applications to make them just right.
Helm Charts: Picture this like a package with all the instructions needed to set up and run your application.
Ksonnet Applications: It's a way to describe your applications using a special language, making it easier to manage.
Jsonnet Files: These are files that help define your application's structure and behavior in a clear way.
Custom Config Management Tool: If you have your own special way of managing configurations, Argo CD can work with that too.

These are just different tools or methods you can use to tell Argo CD how your applications should be set up and run.

Argo CD relies on special files called custom resource definitions (CRDs) to set up and manage its applications in a Kubernetes cluster. These CRDs act like instructions for Argo CD Among them, the Application CRD is particularly important.In Argo CD, an application is like a set of directions that tells the system where to find your code (in a place called a Git repository) and where to place it in a Kubernetes cluster. This Kubernetes cluster can be the same one where Argo CD is operating, or it might be a different one. In simpler terms, the Application CRD is a set of instructions that Argo CD uses to handle your code and deploy it into a Kubernetes cluster.

Argo CD works like a supervisor for applications in a Kubernetes system. It keeps an eye on them all the time. It checks if each application is running the way it's supposed to, according to the plan laid out in a special place called a Git repository. If an application is not doing what it's supposed to do, Argo CD notices and marks it as needing fixing. It shows what's wrong and helps you get it back on track, either by fixing it automatically or with your help.

Argo CD has some cool features! Here are the main ones:

It can work with different ways of organizing and setting up your applications, like Kustomize, Helm and others.
You can use it to manage and put your applications in many different clusters.
It lets you log in using different accounts you might already have, like your GitHub or Microsoft account.
You can set rules to say who can do what in Argo CD, so it's secure.
It can check if your applications are healthy and tell you if something's wrong
If you need to go back to an older version of your application, Argo CD can help you do that.
It can notice if your applications aren't set up the way they should be and show you what's different.
Argo CD has a website where you can see what's happening with your applications in real-time
There's also a special command line tool you can use to make Argo CD do things automatically or work with other tools you use.
You can connect Argo CD to services like GitHub or GitLab so it knows when there are changes to your code.
If you need to do something special before or after updating your application, Argo CD can help with that too.
It can give you data that helps you see how well your applications are doing over time.

In this guide, you'll discover how to:

Use Helm to set up Argo CD on your DOKS cluster (think of Helm like a wizard that helps you install things).
Make sure your applications on the Kubernetes cluster always match what's in a special place called a Git repository. It's like making sure everything is in the right place.
Use Argo CD to put new applications on your cluster and take care of them (like installing and organizing them).

Argo CD helps make sure your applications in the Kubernetes system are running smoothly. It watches over them all the time and ensures two important things:

Keeping everything organized: It uses Application CRDs to make sure everything in your cluster is in the right place.
Installing and managing applications: Argo CD sets up and takes care of applications using Helm, a special tool.

Understanding DOKS and Argo CD: Helm Release Basics

Let's take a look at how Argo CD handles applications made with Helm and stored in a Git repository.

Prerequisites for Completing the Tutorial

To finish this guide, make sure you have:

A working DOKS cluster that you can use. Check the Starter Kit DOKS Setup Guide for details.
A GitHub account and a place to store your Argo CD and application plans. Make sure to create them in advance.
A tool called Git for copying the Starter Kit repository.
Kubectl CLI for talking to your DOKS cluster. Follow the steps here to connect to your cluster using kubectl and doctl.
Argo CLI for giving commands to Argo CD using your computer's command line.
Kubeseal, a tool for keeping secrets safe and talking to the Sealed Secrets Controller.
Helm, a helper tool for managing Argo CD (optional, but a good idea, especially for bigger projects).

Getting to Know Argo CD: Basics of Deploying Applications

Argo CD uses something called an 'Application' to handle how applications are put into action and managed over time. In an Argo CD application plan, you basically tell Argo CD where your application's rules are kept (in a place called Git repository) and where to put your application in a Kubernetes cluster. In simple terms, an Argo CD application is like a connection between your application's rulebook (stored in Git) and the place where it should run (Kubernetes). It's designed to be straightforward and flexible, allowing you to link different rulebooks (from various Git repositories) to different places where your applications should run (Kubernetes clusters)

One great thing about using applications is that you don't have to install Argo CDs separately on each cluster. Instead, you can set up Argo CD on its own cluster and then manage all your applications from there. This means you can deploy your applications to all your clusters from just one spot. This setup helps prevent any problems with Argo CD if other environments run into issues or need to be shut down. It keeps everything running smoothly and safe.

Adding to that, you can organize similar applications into a 'Project.' Projects help you group applications together, sort of like putting them in folders. This is handy when different teams are working on various applications. By default, any new application you create belongs to a basic group called the 'default project.' It's like a default folder that is automatically created. The default project doesn't have any strict rules, and you can change some things about it, but you can't remove it.

The Starter Kit uses the default project to help you quickly get started with Argo CD. Next, you'll discover how to set up an 'Application' for each part of the Starter Kit, using special charts called Helm charts. Argo CD isn't just for Helm charts; you can also use other powerful tools like Kustomize, Ksonnet, Jsonnet, and more. Check out the application sources page for more info on these tools

Although you can use Argo CD's web interface to set up applications, the Starter Kit sticks to a method called GitOps, which uses YAML files. Each YAML file is like a set of instructions for each application and can be stored in a special place called a Git repository. This setup means you can always recreate your Argo CD setup if you need to start over or move to a different cluster. Plus, you can keep track of every change using Git's history feature. It's a good idea to keep your Argo CD setup files in a separate Git repository from the one you use for your application development. For more tips on this, you can check out the best practices page on the official Argo CD documentation website.

Note: It's important to know that Argo CD doesn't automatically set up your new applications. When you create a new application in Argo CD, it's like a red flag saying it's not in sync. This means the plan in the Git repository doesn't match where the application is on the Kubernetes cluster. Just creating a new application in Argo CD doesn't make it automatically appear on your cluster. You need to take an extra step to make sure everything matches up and gets deployed to the right place

To make Argo CDs automatically keep things in sync and clean up unused stuff, you need to set up something called a syncPolicy. This helps Argo CD know when to update or remove things. You can also make Argo CD fix things if someone manually changes something using a tool called kubectl. This way, everything stays on track. If you want to know more about these auto-sync rules, you can check out the official documentation website.

A standard way of telling Argo CD about an application is by using something called an 'Application CRD.' It's like filling out a form. When your application uses a Git repository, the information you give looks something like this:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-apps
namespace: argocd
spec:
project: default
source:
  repoURL: https://github.com/myrepo/my-apps.git
  targetRevision: HEAD
  path: apps
destination:
  server: https://kubernetes.default.svc
  namespace: my-apps
syncPolicy:
  automated:
    prune: true
    selfHeal: true

Let's break down what each part of the setup does:

spec.project: This tells Argo CD which project to use for the application. In this example, it's set to the default project
spec.source.repoURL: This is like telling Argo CD where to find the instructions for your application. It's the web address of a place called Git repository.
spec.source.targetRevision: Think of this like specifying which version of your instructions to use. It can be a branch or tag name.
spec.source.path: This is the specific folder in the Git repository where your application's instructions are stored.
spec.destination.server: This is where your application is supposed to go. It's usually the address of your Kubernetes cluster.
spec.destination.namespace: Think of this like choosing a room for your application in the Kubernetes cluster.
spec.syncPolicy.automated: This turns on a feature that automatically keeps your application in sync with the instructions in the Git repository.
spec.syncPolicy.automated.prune: This is like cleaning up. It decides if Argo CD should remove things from your cluster that are no longer in the instructions.
spec.syncPolicy.automated.selfHeal: If someone manually changes things using a tool called kubectl, this helps Argo CD fix them automatically and keep everything in line.

If you're using Helm charts to manage your applications, you can also use Helm repositories as the source for installing them in your cluster. A typical setup for this looks like the example below. It's similar to using a Git repository, but instead, we're using a Helm chart repository:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: sealed-secrets
namespace: argocd
spec:
project: default
source:
  chart: sealed-secrets
  repoURL: https://bitnami-labs.github.io/sealed-secrets
  targetRevision: 2.4.0
  helm:
    releaseName: sealed-secrets
    values: |
      replicaCount: 2
destination:
  server: "https://kubernetes.default.svc"
  namespace: kubeseal

Let's break down what each part of the setup does:

spec.source.chart: This is the Helm chart that your application will use as its source. Think of it as the blueprint for your application.
spec.source.repoURL: This is the web address where the Helm chart is stored, kind of like where you'd find it in a store.
spec.source.targetRevision: This specifies which version of the Helm chart to use. It's like picking a specific edition of a book to read.
spec.source.helm.releaseName: This is the name that Argo CD will give to the application when it's installed on your Kubernetes cluster. It's like giving your application a name.
spec.source.helm.values: These are extra settings you can give to the Helm chart. It's like telling the chart how you want things to be set up.
spec.destination.server: This is where your application will end up—in your Kubernetes cluster. It's like the destination address.
spec.destination.namespace: This is like choosing a room for your application in the Kubernetes cluster. It's where it will live.

If you want to learn more about how Argo CD works, you can check out the official documentation website. After that, we'll explore different ways to install Argo CD on your Kubernetes cluster:

Setting Up Argo CD on Your Kubernetes Cluster

You can install Argo CD in two ways, either using kubectl or Helm:

Using kubectl and a manifest file: This is the simplest way to install Argo CD. It's a good choice if you're new to Helm installations and just want to get started quickly.
Using Helm: This method gives you more control over how Argo CD is set up and managed. It's recommended for more advanced setups, especially if you're using Argo CD in a production environment or need high availability."

Choosing How to Use Argo CD: Simple Options Explained

Option 1: Multi-Tenant mode

This mode is like having a big apartment building where different teams live. The building is managed by a team that takes care of everything. Each team can use Argo CD through a website, a special program called argocd CLI, or by talking to the building manager (API server).

Option 2: Core only mode

This mode is like having a basic version of something, like a car without all the fancy extras. It doesn't have a fancy screen or special ways to log in. It's just the basic stuff you need to get going.

Starter Kit recommends using Multi-Tenant and High Availability modes to set up Argo CD on your DOKS cluster. This gives you a reliable setup and access to all the features, including a user-friendly interface. For more details, check out the installation guide.

Installing Argo CD with Kubectl is a two-step process:

Create a special place for Argo CD.
Use kubectl to bring Argo CD to life in that place.

Please follow these steps in order:

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml

Now, let's see if everything is installed correctly. First, make sure all the parts of Argo CD are working well:

kubectl get deployments -n argocd

The result you see should be like this (look at the 'READY' column - all the Pods should show as 'running'):

OutputNAME                               READY   UP-TO-DATE   AVAILABLE   AGE
argocd-applicationset-controller   1/1     1            1           51s
argocd-dex-server                  1/1     1            1           50s
argocd-notifications-controller    1/1     1            1           50s
argocd-redis-ha-haproxy            3/3     3            3           50s
argocd-repo-server                 2/2     2            2           49s
argocd-server                      2/2     2            2           49s

For High Availability mode, Argo CD server needs to have at least 2 copies running. If any parts aren't working, check the Kubernetes events and logs for those specific parts.

Using Helm to Install Argo CD

To use this method, you need to have Helm installed on your computer. Starter Kit gives you a pre-made settings file for Helm. This file helps you get started easily and installs Argo CD in High Availability mode (without autoscaling).

Here's what you need to do for the Helm-based installation:

1. If you haven't already, download the Starter Kit folder and open it on your computer.

git clone https://github.com/digitalocean/Kubernetes-Starter-Kit-Developers.git
cd Kubernetes-Starter-Kit-Developers

2. Now, let's add the place where Argo CD is kept using Helm:

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update argo

3. Next, let's look for the different options we have to install Argo CD in the Helm repository:

helm search repo argo

The result you see should look something like this:

OutputNAME                            CHART VERSION   APP VERSION     DESCRIPTION 
argo/argo                       1.0.0           v2.12.5         A Helm chart for Argo Workflows  
argo/argo-cd                    4.9.4           v2.4.0          A Helm chart for Argo CD, a declarative, GitOps...
...

4. Now, let's open and look at the Argo CD settings file provided in the Starter Kit folder. You can use any text editor you like, but it's best to use one that supports YAML linting. For example, you can use VS Code:

code 14-continuous-delivery-using-gitops/assets/manifests/argocd/argocd-values-v4.9.4.yaml

5. At last, let's put Argo CD into action on your DOKS cluster:

HELM_CHART_VERSION="4.9.4"
helm install argocd argo/argo-cd --version "$ {HELM_CHART_VERSION}" --namespace argocd --create-namespace -f "14-continuous-delivery-using-gitops/assets/manifests/argocd/argocd-values-v$ {HELM_CHART_VERSION}.yaml"

Note: We're using a particular version for the Helm chart – in this case, it's version 4.9.4, which corresponds to version 2.4.0 of the application. This is a good habit because it ensures that we get the expected results and makes it easier to keep track of changes using Git

Now, let's see if the installation using Helm was successful:

helm ls -n argocd

The result you see should be something like this (check the 'STATUS' column, it should say 'deployed'):

NAME    NAMESPACE       REVISION        UPDATED                                 STATUS          CHART           APP VERSION
argocd  argocd          1               2022-03-23 11:22:48.486199 +0200 EET    deployed        argo-cd-4.9.4   v2.4.0

At last, let's make sure that Argo CD is deployed and ready to go. We'll check its status:

kubectl get deployments -n argocd

The result you'll see should look something like this (look at the 'READY' column - all the Pods should show as 'running'):

OutputNAME                               READY   UP-TO-DATE   AVAILABLE   AGE
argocd-applicationset-controller   1/1     1            1           2m9s
argocd-dex-server                  1/1     1            1           2m9s
argocd-notifications-controller    1/1     1            1           2m9s
argocd-redis-ha-haproxy            3/3     3            3           2m9s
argocd-repo-server                 2/2     2            2           2m9s
argocd-server                      2/2     2            2           2m9s

To ensure High Availability mode, Argo CD server needs to have at least 2 copies running. If any parts aren't working, please check the Kubernetes events and logs for the specific parts that are having issues.

If you want to learn more about the Argo CD Helm chart, you can check out the community-maintained repository.

Next, we'll show you how to use the graphical user interface provided by Argo CD to access and explore its main features.

Getting Started with the Argo CD Web Interface

Argo CD comes with a cool feature - the web interface. This helps you do important things like managing applications and checking how they're doing. You can create applications and do different tasks easily. Plus, you can see the status of each application, look at events, and check logs. Argo CD also gives you a visual picture of all the parts each application is using in Kubernetes, like pods and replicasets.

To use the web interface, you need to run a command in your terminal. This command helps connect your computer to the Argo CD service. Just type it in your terminal!

kubectl port-forward svc/argocd-server -n argocd 8080:443

Now, go to your web browser and type localhost:8080 in the address bar (don't worry if you see a certificate warning). You'll see the Argo CD login page. The default admin username is 'admin,' and the password was created when you installed Argo CD. You can find it by running the command below:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

After logging in, you'll see the applications dashboard. Here, you can see, make, or handle applications using the user interface. You can also use a YAML editor. Plus, you can sync or refresh things as needed:

If you click on any application, you'll see a visual picture of all the things it's using.

In the next part, you can handle your application projects, repositories, and clusters:

At last, the user info section tells you about the users and lets you update the administrator password:

Feel free to explore every part and detail to discover all the cool features. Next, we'll show you how to use the command line tool called 'argocd.

Exploring Argo CD Through the Command Line

Argo CD offers the same features through both the web interface and the command line tool (CLI). To use the CLI, just open a new terminal window and type 'argocd' without anything else. It will show you all the commands and options you can use.

argocd
Usage:
argocd [flags]
argocd [command]

Available Commands:
account     Manage account settings
admin       Contains a set of commands useful for Argo CD administrators and requires direct Kubernetes access
app         Manage applications
cert        Manage repository certificates and SSH known hosts entries
cluster     Manage cluster credentials
completion  output shell completion code for the specified shell (bash or zsh)
context     Switch between contexts
gpg         Manage GPG keys used for signature verification
help        Help about any command
...

If you ever want help with a command or sub-command, just type 'argocd <command/subcommand> --help'. For instance, if you're curious about the options for the 'app' command:

argocd app --help

The result you see will be something like this:

Manage Applications
Usage:
argocd app [flags]
argocd app [command]

Examples:
# List all the applications.
argocd app list

# Get the details of a application
argocd app get my-app
...

Take some time to check out other commands and options to see what else you can do. Next up, we'll show you how to set up your first Argo CD application, which will deploy all the components from the Starter Kit automatically:

Initializing Your First Argo CD Application

When Argo CD is freshly installed, it doesn't know where to find your applications or which Git repositories to use for getting application details. To help it out, we do a one-time setup called 'bootstrapping.' You can do all the steps in this section using either the argocd command line or the graphical user interface.

There are different ways to set up your cluster (like using scripts), but many Argo CD users follow the 'app of apps' method. This means you begin by creating a main application using the command line or the web interface. This main application then helps set up and start all the other applications in your Kubernetes cluster.

Organizing Your Git Repository Structure

Before we start, let's make sure your Git repository is organized in a specific way. In the example below, you'll see how to create a structure for your Git repository that looks like this:

clusters
└── dev
  └── helm
      ├── cert-manager-v1.8.0.yaml
      ├── nginx-v4.1.3.yaml
      ├── prometheus-stack-v35.5.1.yaml
      ├── sealed-secrets-v2.4.0.yaml
      └── velero-v2.29.7.yaml

Now, open your terminal and do the following steps to set up the structure for your Git repository:

1. First, copy your git repository used for testing Argo CD (make sure to replace the <> placeholders accordingly):

git clone <YOUR_ARGOCD_GIT_REPOSITORY_ADDRESS>

2. Then, go into the folder you just copied and create the structure of folders like this (make sure to replace the <> placeholders accordingly):

cd <YOUR_GIT_REPO_LOCAL_COPY_DIRECTORY>mkdir -p clusters/dev/helm

3. Now, take the application instructions given for each part in the Starter Kit folder (you can also check how they are organized) and copy them:

4. Once you're done, save your changes and push them to the main repository.

Now, it's time to set up the main application, and Argo CD will take care of bringing all Starter Kit applications to your DOKS cluster automatically.

Applying the App of Apps Pattern with Argo CD CLI

In this part, you'll find out how to use the argocdCLI to set up and work with the "app of apps" pattern. This lets you deploy all the components of the Starter Kit on your DOKS cluster. Here's a simple picture to show you what we mean:

To start, open a new terminal window and use a command to connect your local machine to the Argo CD main server.

kubectl port-forward svc/argocd-server -n argocd 8080:443

In another terminal window, you have to make sure the argocd CLI can talk to the Argo CD API server. To do this, you need to log in and verify the argocd client with your Argo CD server.

ADMIN_USER="admin"
ADMIN_PASSWD="$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d)"
argocd login localhost:8080 --username $ADMIN_USER --password $ADMIN_PASSWD --insecure

The result you'll see resembles something like this:

Output'admin:login' logged in successfully
Context 'localhost:8080' updated

Now, enter the following command to create the main application for the Starter Kit apps. Be sure to replace the placeholders like <> with the correct information:

argocd app create starter-kit-apps   --dest-namespace argocd   --dest-server https://kubernetes.default.svc   --repo https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_ARGOCD_GITHUB_REPO_NAME>.git   --path clusters/dev/helm

That command you just used sets up something called an "Argo CD application." Here's what it does:

Creates an Application: It makes a new application in Argo CD called "starter-kit-apps" in the argocd namespace.
Configures it to Work with Our Cluster: It's set to work with the same place where Argo CD is running, which is our local Kubernetes system. This is because of the --dest-server part, which points to our local Kubernetes system at https://kubernetes.default.svc .
Connects to a GitHub Repository: It connects to a GitHub repository specified in the --repo part. This is where it gets all the information it needs to set up our cluster.
Applies the Manifests: It takes all the application files in the clusters/dev/helm directory (--path argument) and puts them into action on our cluster.

Now, you have to make sure everything in the "starter-kit-apps" application is up to date. Argo CD doesn't do this automatically; you need to tell it to sync.

argocd app sync starter-kit-apps

The result you'll see will look something like this:

OutputTIMESTAMP                  GROUP        KIND             NAMESPACE   NAME                       STATUS     HEALTH  ...
2022-03-23T17:39:38+02:00  argoproj.io  Application      argocd      sealed-secrets-controller  OutOfSync  Missing ...            
2022-03-23T17:39:38+02:00  argoproj.io  Application      argocd      velero                     OutOfSync  Missing ...             
2022-03-23T17:39:38+02:00  argoproj.io  Application      argocd      ingress-nginx              OutOfSync  Missing ...
...
GROUP        KIND         NAMESPACE  NAME                       STATUS  HEALTH  HOOK  MESSAGE
argoproj.io  Application  argocd     sealed-secrets-controller  Synced                application.argoproj.io/sealed-secrets-controller created
argoproj.io  Application  argocd     ingress-nginx              Synced                application.argoproj.io/ingress-nginx created
argoproj.io  Application  argocd     kube-prometheus-stack      Synced                application.argoproj.io/kube-prometheus-stack created
argoproj.io  Application  argocd     velero                     Synced                application.argoproj.io/velero created
argoproj.io  Application  argocd     cert-manager               Synced                application.argoproj.io/cert-manager created

Once the previous command is done, check if a new application has appeared on your Argo CD server dashboard. Open a web browser and go to http://localhost:8080. Click on the "Applications" tab, and select the tile named "starter-kit-apps." You'll notice something called the "app of apps" pattern by looking at the composition graph.

You can also take a look at the new applications using the command line:

argocd app list

The information you'll see in the terminal will be something like this:

OutputNAME                       CLUSTER                         NAMESPACE       PROJECT  STATUS     HEALTH   SYNCPOLICY  ...
ingress-nginx              https://kubernetes.default.svc  ingress-nginx   default  OutOfSync  Missing  Auto-Prune  ...
cert-manager               https://kubernetes.default.svc  cert-manager    default  OutOfSync  Missing  Auto-Prune  ...
kube-prometheus-stack      https://kubernetes.default.svc  monitoring      default  OutOfSync  Missing  Auto-Prune  ...
sealed-secrets-controller  https://kubernetes.default.svc  sealed-secrets  default  OutOfSync  Missing  Auto-Prune  ...
starter-kit-apps           https://kubernetes.default.svc  argocd          default  Synced     Healthy  <none>      ...  
velero                     https://kubernetes.default.svc  velero          default  OutOfSync  Missing  Auto-Prune  ...

The main application "starter-kit-apps" will show as in-sync, but the smaller applications inside it will be marked as out of sync. Now, you have two options to get everything in line: either use the web interface or the command line.

argocd app sync -l argocd.argoproj.io/instance=starter-kit-apps

The sync process might take some time, possibly 5-10 minutes, especially if there are many complex Kubernetes objects across all applications.

Once some time has passed, check the list of applications again:

argocd app list

The result you'll see will look like this (make sure to notice that all applications are now in sync):

OutputNAME                       CLUSTER                         NAMESPACE       PROJECT  STATUS    HEALTH   SYNCPOLICY  CONDITIONS ...
ingress-nginx              https://kubernetes.default.svc  ingress-nginx   default  Synced    Healthy  Auto-Prune  <none>     ...
cert-manager               https://kubernetes.default.svc  cert-manager    default  Synced    Healthy  Auto-Prune  <none>     ...
kube-prometheus-stack      https://kubernetes.default.svc  monitoring      default  Synced    Healthy  Auto-Prune  <none>     ...
sealed-secrets-controller  https://kubernetes.default.svc  sealed-secrets  default  Synced    Healthy  Auto-Prune  <none>     ...
starter-kit-apps           https://kubernetes.default.svc  argocd          default  Synced    Healthy  <none>      <none>     ...
velero                     https://kubernetes.default.svc  velero          default  OutOfSync Missing  Auto-Prune  SyncError  …

The Velero application deployment will intentionally fail and remain in the SyncError state. This is a learning opportunity for you to practice diagnosing application issues in Argo CD. Check the Hints section below for guidance on troubleshooting. Setting up the parent application is a one-time task. In the future, whenever there are changes in the Git repository for each application, Argo CD will detect the differences and apply the necessary updates. Argo CD typically checks for changes in your Git repository every 3 minutes by default, using a polling method. Alternatively, you can configure Argo CD to use Git webhooks for faster updates. Refer to the official documentation to learn how to set up and configure Argo CD with Git webhooks.

Hint: If you want to make sure the main application is always kept up to date automatically (and enable features like self-healing and automatic pruning), you can use this command. Just make sure to replace the placeholders like <> with the right information:

argocd app create starter-kit-apps --dest-namespace argocd --dest-server https://kubernetes.default.svc -repo https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_ARGOCD_GITHUB_REPO_NAME>.git --path clusters/dev/helm  --sync-policy automated --auto-prune --self-heal

If something goes wrong during synchronization, you can check the Kubernetes events for that specific application. Just use the command argocd app get <application_name> to take a look.

argocd app get velero

The information you'll see in the terminal will look something like this:

Output Name:        velero
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          velero
URL:                https://argocd.example.com/applications/velero
Repo:               https://vmware-tanzu.github.io/helm-charts
Target:             2.27.3
Path:               
SyncWindow:         Sync Allowed
Sync Policy:        Automated (Prune)
Sync Status:        OutOfSync from 2.27.3
Health Status:      Missing
CONDITION  MESSAGE                                                                                          LAST TRANSITION
SyncError  Failed sync attempt to 2.27.3: one or more objects failed to apply (dry run) (retried 5 times).  2022-03-24 12:14:21 +0200 EET
GROUP                      KIND                      NAMESPACE  NAME                               STATUS     HEALTH      HOOK      MESSAGE
velero.io                  VolumeSnapshotLocation    velero     default                            Failed     SyncFailed  PostSync  error validating data: ValidationError(VolumeSnapshotLocation.spec): missing required field "provider" in io.velero.v1.VolumeSnapshotLocation.spec
velero.io                  BackupStorageLocation     velero     default                            Failed     SyncFailed  PostSync  error validating data: [ValidationError(BackupStorageLocation.spec.objectStorage): missing required field "bucket" in io.velero.v1.BackupStorageLocation.spec.objectStorage, ValidationError(BackupStorageLocation.spec): missing required field "provider" in io.velero.v1.BackupStorageLocation.spec]
...

Now, let's explore how to use the "app of apps" pattern and do the same tasks using the Argo CD graphical user interface.

Deploying Applications with Argo CD Web Interface

In this part, you'll discover how to use the Argo CD web interface to set up and utilize the "app of apps" pattern for deploying all Starter Kit components on your DOKS cluster. Take a look at the picture below to understand the main idea:

As you can see in the diagram above, starting a new application through the web interface is quite similar to using the command line. The only distinction is that you'll move between various panels or windows and use simple point-and-click actions. Argo CD will handle the technical details by creating the necessary application configurations and implementing changes on your Kubernetes cluster.

Begin by opening a web browser and logging in to the Argo CD web console. The default username is "admin," and you can find the default password in:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

After you log in, you'll find yourself on the applications dashboard page, which might be empty if it's a new installation. To start creating a new application, click on the "Create Application" button. A new panel will appear, prompting you for details about the application:

Make sure to complete each field with the following information:

Application Name: Choose a name for the new application (like "starter-kit-apps").
Project: For your first time with Argo CD, you can stick with the default project.
Sync Policy and Sync Options: This configures how syncing works, like whether it's manual or automatic, and the details of retries and intervals.
Source Repository URL: Enter the URL of your GitHub repository. It should look something like https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_ARGOCD_GITHUB_REPO_NAME>.git.
Source Path: Specify the directory path in your GitHub repository where the application manifests are stored. For example, clusters/dev/helm.
Destination Cluster URL: Provide the URL of the target Kubernetes cluster. For the local cluster where Argo CD is running, use https://kubernetes.default.svc.
Destination Namespace: Specify the Kubernetes namespace for Argo CD applications. Usually, it's set to argocd.

Once you've entered all the application details, simply click on the "Create" button at the top. This will add a new tile for your application on the dashboard page.

Clicking on the application tile allows you to see the "app of apps" pattern in action. Check out the composition graph to understand how different components are interconnected.

Observing the picture above, you'll see that all applications are marked as "OutOfSync." To get everything in sync, the next step is to initiate a sync operation on the main application. Click on the "Sync" button on the parent application tile. A new panel will appear on the right side, indicating that all child applications are selected for synchronization.

Keep the default settings as they are, then click on the "Synchronize" button at the top. Watch as Argo CD initiates the sync operation, cascading it to all applications in the hierarchy.

The deployment of the Velero application intentionally fails and remains in the "SyncError" state. This is designed as a learning opportunity for you to become familiar with diagnosing application issues in Argo CD. Check the Hints section below for guidance on troubleshooting.

Assuming everything goes smoothly, you should see all applications with a green border, indicating a healthy and synced status. The initial setup is a one-time task. For any subsequent changes in your Git repository, Argo CD will identify the differences and apply the necessary updates. Argo CD typically checks for changes using a polling mechanism every 3 minutes. If you prefer, you can explore using Git webhooks for more efficient updates. Refer to the official documentation for guidance on setting up and configuring Git webhooks with Argo CD

If you want, you can set the parent application to sync automatically by choosing "Automatic" from the SYNC POLICY dropdown. To enable self-healing and automatic pruning, simply check the boxes for "PRUNE RESOURCES" and "SELF HEAL.

If there are any issues during synchronization, you can check the Kubernetes events for the specific application. Using the web interface, go to the tile of the application that is facing problems:

Next, click on the red-colored "Sync failed" message link in the "LAST SYNC RESULT" section of the application page header. A new panel will appear, providing valuable information about why the sync operation encountered issues.

In the upcoming section, you'll discover how to handle multiple applications simultaneously using a single CRD, known as the ApplicationSet.

Managing Multiple Applications with Argo CD Application Sets

Argo CD Application Sets is a robust feature that brings automation to managing multiple applications. The ApplicationSet Controller, part of the Argo CD project, introduces automation through templated definitions. This feature is especially useful to eliminate redundancy in your application configurations, following the DRY (Don't Repeat Yourself) principle.

The ApplicationSet controller comes bundled with Argo CD, residing in the same namespace. It works by automatically creating Argo CD Applications using the information provided in a new ApplicationSet Custom Resource (CR).

From Argo CD version 2.3.x onward, there's no need for a separate installation of the ApplicationSet Controller. It's automatically included in the main Argo CD installation. In the Starter Kit, we're using a version equal to or greater than 2.3.1, so you don't have to make any additional installations or changes. Everything is ready to go.

Think of an ApplicationSet as a powerful tool that operates with a list of values and a template. This template gets filled in with the values from the list, creating a sequence of applications. In simple terms, you create one ApplicationSet configuration, and it automatically generates as many Argo CD Applications as you need, using the specified values. So, instead of handling multiple application manifests, you manage everything with a single manifest - the ApplicationSet.

ApplicationSets make it easy to handle setups involving multiple clusters and environments by using templates with parameters. Alongside List Generators, there are other types of generators:

Cluster generator: It uses clusters defined in Argo CD to template applications.
Git generator: This one uses files/directories from a Git repository to template applications.

A typical ApplicationSet Custom Resource Definition (CRD) using a List Generator looks like this:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
name: my-app
spec:
generators:
  - list:
      elements:
        - cluster: dev
          url: https://kubernetes.dev.svc
        - cluster: qa
          url: https://kubernetes.qa.svc
        - cluster: prod
          url: https://kubernetes.prod.svc
template:
  metadata:
    name: '{{cluster}}-app'
  spec:
    project: default
    source:
      repoURL: https://github.com/myrepo/my-applicationset.git
      targetRevision: HEAD
      path: clusters/{{cluster}}/my-apps
    destination:
      server: '{{url}}'
      namespace: argocd

Applying the above ApplicationSet to your Kubernetes cluster will create three Argo CD applications. For instance, the application for the development environment is created as shown below:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: dev-app
spec:
project: default
source:
  repoURL: https://github.com/myrepo/my-applicationset.git
  targetRevision: HEAD
  path: clusters/dev/my-apps
destination:
  server: https://kubernetes.dev.svc
  namespace: argocd

Template engines are versatile tools that provide many capabilities. You can explore more about this feature by visiting the main ApplicationSet documentation website.

Removing Argo CD Applications

To remove applications managed by Argo CD, you simply delete the corresponding manifest from your Git repository source. If you've used the app of apps pattern, deleting the parent app (via CLI or web interface) will automatically delete all child applications.

Here's how to delete the starter-kit-apps parent application (and its child apps) using the argocd CLI:

argocd app delete starter-kit-apps

If you want to make sure that the child apps and all their resources are deleted along with the parent app, you need to add the right finalizer to your Application definition.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: cert-manager
namespace: argocd
finalizers:
  - resources-finalizer.argocd.argoproj.io
spec:
...

Look for the added finalizers field in the metadata section of the custom resource manifest. When you delete the application, the linked Kubernetes objects will also be deleted.

Conclusion:

In this guide, you mastered the basics of automating deployments with GitOps using Argo CD. You set up Argo CD applications to handle Helm releases automatically and deployed all the components of the Starter Kit in a GitOps manner. You also learned how to kickstart new Argo CD applications using the app of apps pattern and simplify application creation with ApplicationSets.

Ready to explore the resource usage of the Starter Kit? Dive into the Starter Kit Resource Usage chapter to learn more!